								
                                                                   11/22/00


x86 ROM Boot Loader:
--------------------

This x86 ROM-based boot loader is an alternative to LoadCEPC and was designed
in such a way that it doesn't require BIOS or DOS services for the x86
platforms that it supports.  In its default state, the loader replaces the
system BIOS (in flash/ROM) and initializes the hardware, as the BIOS would,
before providing OS image loading services.  As a first release, the loader
supports most of the Lanner & Advantech offerings (EM350, EM351, PCM5822, etc.).
Note that the loader hasn't been tested on any of the National Semiconductor
Geode-based reference platforms.

The boot loader can also be easily modified to preserve the BIOS and yet
provide OS image loading options.  In this scenario, the loader can be launched
by the BIOS from ATA disk or Compact Flash for example (or as a BIOS 
extension).  Note that this requires that the BIOS support the boot device as 
well as a boot sector image to load the boot loader to RAM (not provided) in 
the same fashion that the DOS boot sector loads io.sys into memory.

The boot loader supports downloading an image over Ethernet (using DHCP or
by static IP) as well as from a local IDE/ATA hard disk (where the nk.bin image 
is placed in the root directory of the active partition).  Future revisions will
add support for booting from Compact Flash.

Source Organization:
--------------------

The code that makes up the boot loader is spread across the following 
directories:

%_WINCEROOT%\platform\geode\romboot - build files (BIB, batch, etc.)
%_WINCEROOT%\public\common\oak\csp\i486\romboot - common boot loader code
%_WINCEROOT%\public\common\oak\csp\i486\geode\romboot - Geode/MediaGX code
%_WINCEROOT%\public\common\oak\drivers\ethdbg\blcommon - more common loader code
%_WINCEROOT%\public\common\oak\drivers\ethdbg\eboot - common download code
%_WINCEROOT%\public\common\oak\drivers\ethdbg\rtl8149 - RealTek 8139 driver
%_WINCEROOT%\public\common\oak\drivers\ethdbg\ne2000 - NE2000 driver
%_WINCEROOT%\public\common\oak\drivers\ethdbg\smc9000 - SMC 9000 driver

Porting to Other x86 Platforms:
-------------------------------

The following changes are required (at a minimum) to add support for a new x86
platform.  Note that other changes may be required based on the chosen platform.

1. The following functions need to be implemented for the new platform (listed
   in calling order):

* BridgeConfig (required):
  This function performs the initial "northbridge" configuration (programming
  the SDRAM controller).  The CPU is executing in protected mode at this point
  and the stack is available.

* BridgePrintConfig (required):
  This function optionally displays bridge configuration information.

* PlatformInit (required):
  This function performs any "southbridge", "super I/O", and ancillary platform
  configuration. 

2. The following globals need to be implemented to support the PCI enumeration 
process.  They define the valid range of memory and I/O address available to 
the enumerator for assignment to PCI functions:

* ULONG g_nPCI_BUS0_MEM_BASE  = Base Memory Space Address
* ULONG g_nPCI_BUS0_MEM_LIMIT = Limit Memory Space Address
* ULONG g_nPCI_BUS0_IO_BASE   = Base I/O Space Address
* ULONG g_nPCI_BUS0_IO_LIMIT  = Limit I/O Space Address

3. The network adapter type, defined in the boot args (function InitBootArgs()),
   should be updated to accurately reflect the platform download/edbg NIC.

4. Boot.bib should be reviewed against the new platform's memory configuration. 
   As well, the sources file may need to be updated to include the new platform 
   library (e.g., the above code).


Building the Loader:
--------------------

Running "build" from the ROMBOOT directory or running the provided  batch file 
(b.bat) will build the loader.  The batch file is useful for rebuilding all of
the code upon which the loader is dependent.  The build creates the component 
libraries (NIC drivers, eboot, platform, etc.), then links and runs romimage on 
the image (note that it assumes you've already done a Geode platform build and
have sysgened the header files and libraries).

The result of the build is a romboot.rom image that can be flashed onto the 
platforms system flash/ROM chip.


Known Issues:
-------------

The following are known issues when using the boot loader in the default
configuration (e.g., to replace the system BIOS).  Note that many of the issues
may not exist if the BIOS remains and loader is used for image loading only.

* DRAM sizing
  The configuration code doesn't perform DRAM sizing.  Currently, the
  implementation supports and has been tested on 32MB and 128MB configurations.
  The DRAM configuration needs to be statically defined at build time (see
  the BridgeConfig() function in the ...\csp\i486\geode\romboot directory).

* VGA linear framebuffer (flat) video driver
  The boot loader doesn't support the flat video driver (since there's no VESA
  BIOS implementation).  As such, the platforms native driver (or the VGA
  driver) should be used (...\csp\i486\geode\gxvideo).

* Geode audio
  The audio function on the Geode southbridge (CS5530/A) isn't supported.  The
  audio implementation makes use of a software library (VSA - Virual System 
  Architecture) that's normally implemented as part of the BIOS, but isn't
  included in the boot loader code.


Features To be Added:
---------------------

* Support loading OS image from Compact Flash ATA disk.
* DRAM sizing.
* Other sample platform implementations.
* Flash-update code to support new loader updates.
* FAT/IDE write capabilities to support new OS image download to disk/CF.
* Program to store loader to flash or store on disk/CF (and add boot sector
  code to launch loader).

Troubleshooting:
----------------

* Hook up a terminal emulator (e.g., hyperterm or ceterm) to COM1 and configure
  it for 38400 N-8-1 and No Flow Control.  The loader will display status and 
  error information over the connection.
* Check the state of the "usedhcp" environment variable (e.g., with a terminal
  emulator program, halt the loader boot process and type "set" to display the
  environment variables).  When set to "1", the loader will use a DHCP server
  to obtain its IP address.  When set to "0", it'll use  the values assigned to
  "ip" and "subnet".  Make sure the correct settings are being used for the
  network connection being used.
* After setting a loader variable with the "set" command, make sure you
  execute a "store" to save the settings to CMOS if you want them to persist
  across system reboots.
* When booting from a hard drive, if romboot can't locate nk.bin, the problem
  may be that you don't have a valid MBR on the drive (run "fdisk /mbr").
